home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / fortran / libry51.zip / LIBRY5.DOC < prev    next >
Text File  |  1989-11-10  |  14KB  |  349 lines
  1. .pa
  2.                             FILE HANDLING ROUTINES
  3.  
  4. FORTRAN is rather ill suited to file I/O. It is painfully slow compared to the
  5. actual  speed  of  memory-to-disk  transfers.  I have developed  this  set  of
  6. procedures to allow fast file access from FORTRAN. On the HP-1000F and HP-A900
  7. these  routines  provide a speed increase factor of about 20.  On the  PC  the
  8. speed  increase is more like 30 for FORTRAN/V3.31 and 3 for FORTRAN/V4   It
  9. may  seem  a  little circuitous at first to always read  and  write  character
  10. strings  instead  of  numbers and to call some subroutine rather  than  simply
  11. using "WRITE" and "READ" statements; but once you get used to it,  it isn't so
  12. bad; and the speed is worth a little extra trouble.
  13.  
  14. As far as numbers go, you can use DEC0DE to decode  them  from  the  character
  15. strings and "WRITE(CBUF,1000)" to encode them.
  16.  
  17. I  have  allowed for only four sequential access files and one  random  access
  18. file. It's not obvious in FORTRAN, but you can't just open an unlimited number
  19. of  files.  If you need more you can always access the binary file  procedures
  20. directly  (e.g.   BOPEN).  You can open as many files with BOPEN as there  are
  21. FILES=?? allocated in your CONFIG.SYS file.
  22.  
  23. A  word  of  warning about reading files created by word  processors  and  the
  24. like... these procedures ignore control characters on either read or write and
  25. chop-off trailing blanks on write.  Also, files must end with the standard EOF
  26. character (zero record length for HPs or ctrl-Z for PCs). This is done for you
  27. automatically  by  the end-file functions and most editors (at least  WED  and
  28. IBM's  Professional  Editor).   If you create a file using FORTRAN on  the  PC
  29. WITHOUT these procedures and then attempt to read it WITH these procedures you
  30. will  get  trash  at the end unless you put a CHAR(26)  on the last  line  (A1
  31. format) before you close the file.
  32.  
  33. Another  word  of caution.  Do not mix Microsoft's FORTRAN file I/O and  these
  34. routines.   The  only thing that I know it messes up is the  directory  search
  35. functions (DIRSET and DIRNXT);  however,  one can't be sure.  You see there is
  36. this  special area at the top of your program called a program segment  prefix
  37. (PSP) which contains an important data transfer area (DTA). FORTRAN moves this
  38. area off into the twilight zone; whereas, these routines leave it alone.  They
  39. just aren't compatible.
  40. .pa
  41.                    QUICK LIST OF FILE HANDLING SUBROUTINES
  42.  
  43. BCLOSE... binary file close
  44. BCREAT... binary file open (status='unknown')
  45. BMFP..... move binary file pointer
  46. BOPEN.... binary file open (status='old')
  47. BPURGE... binary file purge/delete
  48. BREAD.... binary file read
  49. BWRITE... binary file write
  50. DIRNXT... get next entry in directory
  51. DIRSET... set up for directory search
  52. ECLOS.... close random access file
  53. EOPEN.... open random access file
  54. EREAD.... read random access file
  55. EWRIT.... write random access file
  56. FBKSP1... backspace first sequential access file
  57. FCLOS1... close first sequential access file
  58. FENDF1... end (affix EOF marker to) first sequential access file
  59. FEXIST... logical check for file exist
  60. FOPEN1... open first sequential access file
  61. FREAD1... read first sequential access file
  62. FRWND1... rewind first sequential access file
  63. FWRIT1... write first sequential access file
  64. GETPSP... get the program segment prefix (PC only - on HP use GETST)
  65. RRPAR.... get file name from runtime string
  66.  
  67. also available are:
  68.  
  69.      FWRIT2, FBKSP2, FCLOS2, FENDF2, FOPEN2, FREAD2, and FRWND2.
  70.      FWRIT3, FBKSP3, FCLOS3, FENDF3, FOPEN3, FREAD3, and FRWND3.
  71.      FWRIT4, FBKSP4, FCLOS4, FENDF4, FOPEN4, FREAD4, and FRWND4.
  72.  
  73. A note about binary file routines:
  74.  
  75.      These are not available on the HP. They are absolute file I/O. There
  76.      is  no  consideration of record separators,   line-feeds,   carriage
  77.      return, or end of file markers. This applies to reading and writing.
  78. .pa
  79. NAME:     BCLOSE
  80. PURPOSE:  close a binary file
  81. TYPE:     subroutine (far external)
  82. SYNTAX:   CALL BCLOSE(IHAND)
  83. INPUT:    IHAND (INTEGER*2) file handle (see BOPEN)
  84. OUTPUT:   none
  85.  
  86.  
  87. NAME:     BCREAT
  88. PURPOSE:  open a binary file and create if not already exist
  89. TYPE:     subroutine (far external)
  90. SYNTAX:   CALL BCREAT(NAME,ICODE,IHAND,IERR)
  91. INPUT:    NAME (CHARACTER*(*)) ASCIIZ string (the last character MUST be a
  92.           CHAR(0)! or else disaster may result)
  93.           ICODE (INTEGER*2) open code (see BOPEN)
  94. OUTPUT:   IHAND (INTEGER*2) file handle (see BOPEN)
  95.           IERR (INTEGER*2) error indicator (see BOPEN)
  96.  
  97.  
  98. NAME:     BMFP
  99. PURPOSE:  move binary file pointer
  100. TYPE:     subroutine (far external)
  101. SYNTAX:   CALL BMFP(IHAND,NBYTES,IERR)
  102. INPUT:    IHAND (INTEGER*2) file handle (see BOPEN)
  103.           NBYTES (INTEGER*4 note unsigned long integer!) number of bytes from
  104.           the beginning of the file where you want the pointer to be
  105.           positioned (e.g. NBYTES=INT4(0) is a rewind)
  106. OUTPUT:   IERR (INTEGER*2) error indicator (IERR=1 indicated invalid handle)
  107.  
  108.  
  109. NAME:     BOPEN
  110. PURPOSE:  open an existing binary file
  111. TYPE:     subroutine (far external)
  112. SYNTAX:   CALL BOPEN(NAME,ICODE,IHAND,IERR)
  113. INPUT:    NAME (CHARACTER*(*)) ASCIIZ string (the last character MUST be a
  114.           CHAR(0)! or else disaster may result)
  115.           ICODE (INTEGER*2) open code (see chart below)
  116.                  bit 7 6 5 4 3 2 1 0
  117.                      . . . . . . . 1  read only
  118.                      . . . . . . 1 .  hidden
  119.                      . . . . . 1 . .  system
  120.                      . . . . 1 . . .  volume label
  121.                      . . . 1 . . . .  subdirectory
  122.                      . . 1 . . . . .  archive
  123.                      . 1 . . . . . .  unused
  124.                      1 . . . . . . .  unused
  125. OUTPUT:   IHAND (INTEGER*2) file handle (you must keep track of this and use
  126.           it every time you refer to the file)
  127.           IERR (INTEGER*2) error indicator
  128.                IERR= 2  file not found or invalid file name
  129.                IERR= 3  path not found or invalid path name
  130.                IERR= 4  no handles available (too many files already open)
  131.                IERR= 5  access denied (protected file)
  132.                IERR=12  invalid access code
  133.  
  134.  
  135. NAME:     BPURGE
  136. PURPOSE:  purge/delete an existing file
  137. TYPE:     subroutine (far external)
  138. SYNTAX:   CALL BPURGE(NAME)
  139. INPUT:    NAME (CHARACTER*(*)) ASCIIZ string (the last character MUST be a
  140.           CHAR(0)! or else disaster may result)
  141. OUTPUT:   none
  142.  
  143.  
  144. NAME:     BREAD
  145. PURPOSE:  read from a binary file (what's in there is what you get-literally!)
  146. TYPE:     subroutine (far external)
  147. SYNTAX:   CALL BREAD(IHAND,LREC,CBUF,LBUF,IERR)
  148. INPUT:    IHAND (INTEGER*2) file handle (see BOPEN)
  149.           LREC (INTEGER*2) size of buffer to be read in bytes (unsigned
  150.           integer - can go up to 65535)
  151. OUTPUT:   CBUF (CHARACTER*(*)) buffer
  152.           LBUF (INTEGER*2) actual number of bytes read (you must check for
  153.           end of file, LBUF can be zero)
  154.           IERR (INTEGER*2) error indicator
  155.                IERR=5  access denied (protected file)
  156.                IERR=6  invalid handle
  157.  
  158.  
  159. NAME:     BWRITE
  160. PURPOSE:  write to a binary file (what you put in there is what will be in
  161.           there, literally!)
  162. TYPE:     subroutine (far external)
  163. SYNTAX:   CALL BWRITE(IHAND,LREC,CBUF,IERR)
  164. INPUT:    IHAND (INTEGER*2) file handle (see BOPEN)
  165.           LREC (INTEGER*2) size of buffer to be written in bytes (unsigned
  166.           integer - can go up to 65535)
  167.           CBUF (CHARACTER*(*)) buffer
  168. OUTPUT:   IERR (INTEGER*2) error indicator
  169.                IERR=5  access denied (protected file)
  170.                IERR=6  invalid handle
  171.                IERR=7  write error or insufficient space
  172.  
  173.  
  174. NAME:     DIRNXT
  175. PURPOSE:  get next entry in directory (see DIRSET)
  176. TYPE:     subroutine (far external)
  177. SYNTAX:   CALL DIRNXT(NAME)
  178. INPUT:    none
  179. OUTPUT:   NAME (CHARACTER*12) next matching name (blank indicates no more
  180.           matches)
  181.  
  182.  
  183. NAME:     DIRSET
  184. PURPOSE:  set up for directory search
  185. TYPE:     subroutine (far external)
  186. SYNTAX:   CALL DIRNXT(NAME)